X121 XReplay
ابزار پخش مجدد کندل‌ها در متاتریدر ۵
TradingView-Style Candle Replay Tool for MetaTrader 5
۱. شرح نیازمندی
۱.۱ مسئله
معامله‌گران برای تمرین و بک‌تست دستی استراتژی‌های خود به ابزاری نیاز دارند که بتواند
کندل‌های بازار را از یک نقطه زمانی مشخص پنهان کند و سپس به‌صورت تدریجی
(کندل به کندل) آن‌ها را نمایش دهد. این قابلیت در پلتفرم TradingView با نام
Bar Replay وجود دارد، اما در MetaTrader 5 به‌صورت پیش‌فرض
در دسترس نیست.
۱.۲ نیازمندی‌های عملکردی
| # | نیازمندی | توضیح |
|---|
| ۱ | پنهان‌سازی کندل‌ها | کندل‌های بعد از نقطه cutoff باید از دید کاربر پنهان شوند |
| ۲ | نمایش تدریجی | امکان نمایش کندل‌ها یکی‌یکی با دکمه یا کیبورد |
| ۳ | پخش خودکار | امکان پخش خودکار کندل‌ها با سرعت قابل تنظیم |
| ۴ | بازنشانی | امکان بازگشت به نقطه شروع با یک کلیک |
| ۵ | تغییر تایم‌فریم | حفظ وضعیت Replay هنگام تغییر تایم‌فریم چارت |
| ۶ | بازیابی خودکار | بازیابی خودکار حالت چارت پس از حذف اندیکاتور |
۱.۳ محدودیت‌های فنی MQL5
- امکان حذف یا پنهان‌سازی مستقیم کندل‌های واقعی وجود ندارد
- اندیکاتور نمی‌تواند داده‌های تاریخی را تغییر دهد
- مدیریت رویدادهای چارت محدود به
OnChartEvent است
- ذخیره‌سازی وضعیت بین جلسات نیازمند Global Variables یا فایل است
۲. معرفی ابزار
۲.۱ مشخصات کلی
| مشخصه | مقدار |
|---|
| نام | X121 XReplay |
| نوع | اندیکاتور (Indicator) |
| پلتفرم | MetaTrader 5 (MQL5) |
| نسخه | 1.00 |
| فایل | x-saherelm.x121.x-reply.mq5 |
| مسیر نصب | MQL5/Indicators/ |
| وابستگی | x-saherelm.common.lib.mq5 |
| توسعه‌دهنده | هادی خزاعی اصل |
| شرکت | فن آوران ساحر علم (SaherElm IT Center) |
۲.۲ روش کار
ابزار از روش DRAW_COLOR_CANDLES با ۵ بافر برای رسم کندل‌ها استفاده می‌کند.
کندل‌های واقعی چارت با تغییر استایل چارت (تبدیل رنگ‌ها به CLR_NONE)
پنهان می‌شوند و کندل‌های Replay توسط بافرهای اندیکاتور رسم می‌شوند.
۲.۳ بافرها
| بافر | نوع | کاربرد |
|---|
pBarOpenBuffer | INDICATOR_DATA | قیمت Open |
pBarHighBuffer | INDICATOR_DATA | قیمت High |
pBarLowBuffer | INDICATOR_DATA | قیمت Low |
pBarCloseBuffer | INDICATOR_DATA | قیمت Close |
pBarColorBuffer | INDICATOR_COLOR_INDEX | ایندکس رنگ کندل |
۲.۴ ایندکس‌های رنگ
| ایندکس | نام | کاربرد |
|---|
| 0 | hideColorIDX | کندل پنهان (CLR_NONE) |
| 1 | bullishColorIDX | کندل صعودی (clrDodgerBlue) |
| 2 | bearishColorIDX | کندل نزولی (clrDarkOrange) |
| 3 | neuturalColorIDX | کندل خنثی |
۲.۵ پارامترهای ورودی
| گروه | پارامتر | پیش‌فرض | توضیح |
|---|
| Replay Settings | startBar | 20 | تعداد کندل‌های cutoff |
autoPlaySpeed | 1000 | سرعت پخش خودکار (ms) |
| Presentation | panelButtonTextColor | clrYellow | رنگ متن دکمه‌ها |
panelBackgroundColor | clrBlack | رنگ پس‌زمینه پنل |
infoColor | clrWhite | رنگ متن اطلاعات |
infoPanelBorderColor | clrBlack | رنگ حاشیه پنل |
۲.۶ کنترل‌ها
| دکمه | متن | عملکرد | کیبورد |
|---|
| Prev | |< | یک کندل به عقب | ← / ↓ |
| Play | > | شروع پخش خودکار | Space |
| Pause | || | توقف پخش | Space |
| Next | >| | یک کندل به جلو | → / ↑ |
| Reset | R | بازنشانی به نقطه شروع | R |
۳. معماری فنی
۳.۱ ساختار فایل
| بخش | محتوا |
|---|
#region Imports | کتابخانه‌های مورد نیاز |
#region Definitions | ثابت‌ها، ساختار XChartStyle، ایندکس‌های رنگ |
#region Inputs | پارامترهای ورودی کاربر |
#region Buffers | تعریف ۵ بافر و پلات |
#region Variables | متغیرهای سراسری |
#region Event Handlers | OnInit، OnDeinit، OnCalculate، OnTimer، OnChartEvent |
#region Custm Functions | توابع کمکی و اعتبارسنجی |
#region Value Calculators | محاسبه مقادیر بافرها |
#region Chart Style | مدیریت استایل چارت |
#region UI | پنل کنترل و دکمه‌ها |
#region Control Actions | اکشن‌های پخش |
#region TimeFrame Change | مدیریت تغییر تایم‌فریم |
۳.۲ ساختار XChartStyle
این ساختار ۲۱ فیلد دارد و برای ذخیره و بازیابی کامل حالت چارت استفاده می‌شود:
| دسته | فیلدها |
|---|
| شناسایی | chartId, mode |
| نمایش | showBidLine, showAskLine, showGrid, showVolumes, showTradeLevels, autoScroll, quickNavigation |
| رنگ‌ها | foreGroundColor, backGroundColor, upColor, downColor, bullishColor, bearishColor, gridColor, bidLineColor, askLineColor, lineColor, stopColor, volumesColor |
۳.۳ مکانیزم پنهان‌سازی
- ReadChartStyle: خواندن حالت فعلی چارت و ذخیره در
xReplyChartStyle
- SaveChartStyleToFile: ذخیره در فایل باینری با
FileWriteStruct
- ساخت clearStyle: کپی از حالت اصلی با رنگ‌های
CLR_NONE
- HideBars: اعمال
clearStyle بر چارت → کندل‌های واقعی نامرئی می‌شوند
۳.۴ مکانیزم رسم کندل‌های Replay
- OnCalculate: پر کردن بافرهای OHLC از داده‌های واقعی
- UpdateVisibleColors: تنظیم رنگ بافر بر اساس وضعیت Replay
- کندل‌های قبل از cutoff → رنگ عادی (صعودی/نزولی)
- کندل‌های بعد از cutoff →
hideColorIDX (پنهان)
- کندل‌های قابل نمایش Replay → رنگ عادی (صعودی/نزولی)
۳.۵ مدیریت تغییر تایم‌فریم
هنگام تغییر تایم‌فریم (OnDeinit با REASON_CHARTCHANGE):
- محاسبه ایندکس آخرین کندل نمایش داده شده
- ذخیره زمان آن کندل در Global Variable
- ذخیره وضعیت فعال بودن در Global Variable
- ذخیره تعداد کندل‌های قابل نمایش در Global Variable
در تایم‌فریم جدید (OnInit):
- بررسی وجود Global Variables
- یافتن اولین کندل در تایم‌فریم جدید که شامل زمان ذخیره‌شده است
- تنظیم
xReplyStartBarIndex بر اساس کندل یافت‌شده
- بازیابی تعداد کندل‌های قابل نمایش
- حذف Global Variables
۴. فرآیند و مراحل انجام کار
۴.۱ خلاصه مراحل توسعه
| مرحله | شرح | نتیجه |
|---|
| ۱ | تحلیل نیازمندی و بررسی محدودیت‌های MQL5 | شناسایی روش پنهان‌سازی |
| ۲ | طراحی معماری با DRAW_COLOR_CANDLES | تعریف ۵ بافر و ۴ رنگ |
| ۳ | پیاده‌سازی مدیریت Chart Style | ساختار XChartStyle با ۲۱ فیلد |
| ۴ | پیاده‌سازی ذخیره/بازیابی فایل باینری | FileWriteStruct / FileReadStruct |
| ۵ | پیاده‌سازی پنل UI و کنترل‌ها | ۵ دکمه + برچسب اطلاعات |
| ۶ | پیاده‌سازی میانبرهای کیبورد | Arrow Keys + Space + R |
| ۷ | پیاده‌سازی تایمر و پخش خودکار | StartTimer / StopTimer |
| ۸ | پیاده‌سازی مدیریت تغییر تایم‌فریم | Global Variables |
| ۹ | بهینه‌سازی و تست نهایی | نسخه 1.00 |
۴.۲ تصمیمات فنی کلیدی
| تصمیم | دلیل |
|---|
| استفاده از DRAW_COLOR_CANDLES | کارآمدترین روش رسم کندل در MQL5 بدون ایجاد اشیاء گرافیکی |
| پنهان‌سازی با CLR_NONE | تنها روش ممکن برای نامرئی کردن کندل‌های واقعی بدون حذف آن‌ها |
| ذخیره Chart Style در فایل باینری | بازیابی خودکار پس از حذف اندیکاتور یا کرش ترمینال |
| Global Variables برای تایم‌فریم | حفظ وضعیت بین OnDeinit و OnInit هنگام تغییر تایم‌فریم |
| تایمر فقط در حالت Play | بهینه‌سازی مصرف CPU در حالت Pause |
۴.۳ ساختار کدنویسی
کد بر اساس دستخط کدنویسی شرکت فن آوران ساحر علم نوشته شده است:
- بلوک‌بندی با
#region / #endregion
- کامنت‌های ساختاریافته با
//
- پیشوند
xReply برای متغیرهای مربوط به Replay
- توابع استاندارد:
ValidateInputs، InitRequirements، DefineBuffers، SetIndicatorName
- مدیریت خطا با الگوی
has / result
- پاکسازی منابع در
OnDeinit
۵. راهنمای استفاده
۵.۱ نصب
- فایل
x-saherelm.x121.x-reply.mq5 را در مسیر MQL5/Indicators/ قرار دهید
- در MetaEditor با F7 کامپایل کنید
- اندیکاتور را از Navigator روی چارت بکشید
- پارامتر
startBar را تنظیم کنید (تعداد کندل‌های cutoff)
۵.۲ استفاده
- با → یا ↑ یک کندل به جلو بروید
- با ← یا ↓ یک کندل به عقب برگردید
- با Space پخش خودکار را شروع/متوقف کنید
- با R به نقطه شروع برگردید
- تایم‌فریم را آزادانه تغییر دهید — وضعیت حفظ می‌شود
۵.۳ حذف
با حذف اندیکاتور از چارت، حالت چارت به‌طور خودکار بازیابی می‌شود،
فایل Chart Style حذف می‌شود و اشیاء UI پاک می‌شوند.
✅ نکته: در صورت کرش ترمینال، فایل Chart Style باقی می‌ماند و در اجرای بعدی
به‌جای خواندن از چارت، از فایل خوانده می‌شود. این تضمین می‌کند که حالت چارت همیشه درست بازیابی شود.